'Programming the Apple IIgs in Assembly Language' book review
By Richard Bennett
Copyright (c) 1990 Apple Users' Group, Sydney
Republished from Applecations, a publication of the Apple Users' Group, Sydney, Australia.
I was a bit hesitant to review a book at first, as I don't usually read the entire text of technical publications. I prefer to skim them and only read the parts of interest, and the parts I can understand. With the IIgs, there are heaps of books on programming in assembler, and unfortunately most of them are quite bad. The usual format seems to be for the author to simply type up all he knows about the machine, and leave it at that. Even the covers of most books are quite boring, this one included.
It wasn't until I was told that the authors were Eyes and Lichty, that I basicly said 'give it here!'. Ron Lichty is the manager of the Apple II Developer Tools Group at Apple Inc., and David Eyes is the manager of the Developer Tools Group. Ron co-wrote the original Apple IIgs sales demo (the one with the sax player), as well as many other Apple II products, and David managed the development of APW. Together they wrote 'Programming the 65816: Including the 6502, 65C02, and 65802' (PT65816), the definitive book on the 65816, and played a major role in Bill Mensch's development of the 65816.
On opening the front cover, you'll find quotes of praise about the book by such luminaries as David Krathwohl (Nibble), Bill Basham (DSR), Cecil Fretwell (Call -A.P.P.L.E. R.I.P.) and Jim Merritt (IIgs Finder project leader). With such a list of references, there must be something more to this than your average book on programming. Even so, the actual text of the book is quite short, in fact only the first 260 pages are actually the tutorial. The other 200 odd pages are taken up with the usual appendices of instruction sets and ASCII charts. But don't let that fool you!
I've read (skimmed) quite a few books on programming the IIgs, and they all seem to have the same flaws. That is, they expect you to at least know how to assemble and run something, and/or they are simply modifications of the text in the Toolbox manuals, and/or they simply don't go far enough to let the user continue on after reading it. Fortunately, 'Programming the Apple IIgs in Assembly Language' (PAGSAL) is not such a book.
Chapter one starts off with an introduction to the desktop environment, with most emphasis placed on trying to convince Apple // text based programmers how important full IIgs graphics based programs are. Examples are given, and the chapter wraps up with a couple of pages stressing the importance of event-driven programming in the desktop environment.
Chapter two then covers the architecture and design of the 65816. Although being quite technical at times, this section is indispensable for programmers converting over from the 6502. Considering that their previous book was entirely devoted to this subject, the chapter does seem a bit
cramped, however the information is quite understandable for those with knowledge of the 6502.
The next two chapters cover the use and syntax of APW and the 65816. They start with simple commands such as 'SHOW LANGUAGE', and end up with sample looping constructs and APW directives. For a 6502 programmer who has just bought APW and attempted to read the manual, these two chapters would be a life saver.
The rest of the tutorial section (nine chapters), covers the mandatory code samples such as drawing and manipulating menus, handling dialogs, loading files, and using Quickdraw II. The beauty of these chapters, is that all the text and examples and littered with subliminals (if there is such a thing as subliminal text) about structured programming, the correct ways of doing things, and the actual logic and theory behind the IIgs Toolbox. And this is no wonder, considering the people who helped proof the text, which included Steve Glass (an Apple engineer who wrote much of the IIgs Toolbox), and Jim Merritt (co-author of Finder, and formerly manager of Apple II Developer Technical Support).
As is the trend in technical books, the final result is a IIgs desktop shell program, which is included in it's entirety in one of the appendices, which of course doesn't do very much. The difference, is that other books show direct code examples, and attempt to describe how they work. In PAGSAL, the emphasis is on HOW to do something, with examples coming a delicate second.
So how does PAGSAL rate with a few of the standard questions that IIgs programmers ask?
Q: Does it give a complete explanation of how to maintain an image within a window, re-size it, and still keep the image within the window?
A: This is the first book I've come across that actually states 'This is the way it is done!'. Although it does get a bit thin when you get to how many GrafPorts are required, and how to get multiple windows going, the information is there, and not as twisted and airy fairy as other books. It even briefly discusses code optimisation for window updates etc..
Q: Does it mention routines that can be called by the Toolbox through a window or like definition (user exits)?
A: Whilst updating windows, they describe how to write a routine that is actually called by the Toolbox, and how to handle saving the environment and switching direct pages.
Q: Does it cover driving events through TaskMaster and GetNextEvent?
A: TaskMaster is handled in the usual way, but GetNextEvent is only partially mentioned, and definitely not enough to be usable on the first try.
Q: Are handles and memory (my personal favourite) explained?
A: Memory management is discussed quite well. Although memory mapping is not even touched, the theory behind IDs and handles is quite thorough.
Q: What about dialog and control obscurities?
A: Dialogs are covered well, with an example using StatText, Radio buttons, Simple buttons, and an Icon. However, the Control Manager is not touched.
Lastly, there is a section on assembly language concepts. This covers the mandatory topics of bit manipulation and logic instructions, as well as sections on BCD, flow control and general assembly language theory.
Flaws. Apart from the fact that they actually use APW (joke), PAGSAL fits it's niche quite well. For an Apple // or 6502 programmer, this is one of the better books available (the best I've read anyway). In a world of professional authors, it's pleasing to find two people as dedicated to the IIgs as Ron and David come up with such an introductory book. What starts out as simply an updated version of PT65816, turns out to be a book not just introducing the IIgs, but answering most of the more popular questions about it's internals. Who better to write such a book, than the people in DTS?
It is debatable whether you can flaw a book, unless the information contained in it is incorrect, which in this case it definitely is not. What can be said however, is that if you're a first time assembler programmer, then you'll probably get lost in the second chapter. Although an attempt has been made at covering absolute beginners, the result is still incomplete. At the other end of the scale, it ends with a simple desktop shell (which can be purchased on disk by sending off the card in the back of the book), and some ideas for future projects. However, it still ends without much of a conclusion.
For the more technically minded, there is a summary of PT65816 in one complete chapter, and more importantly the answers to 'those questions'. Much of what a IIgs programmer learns is trial and error. With eventually discovering how things are done as far as the Toolbox is concerned, it is refreshing to see the answers finally in black and white, and to verify their correctness. And with most of the people involved in the book actually working for Apple in the U.S., you can pretty much take the answers as gospel.
Although it only covers a few topics of the quite extensive IIgs Toolbox, 'Programming the Apple IIgs in Assembly Language' is a great book for Apple // programmers taking on the IIgs.
Special thanks must go to Ron Lichty and David Eyes for the interest they have shown in the club by donating the book. I am sure that PAGSAL will be used extensively by our members when it is put in the club library.
'Programming the Apple IIgs in Assembly Language' and 'Programming the 65816: Including the 6502, 65C02, and 65802' are published by Brady Books, and should be available at any computer book shop.

THIS CONTENT COPYRIGHT © 2007, APPLE MACINTOSH USERS' GROUP, SYDNEY
Permission has been obtained to make this material available on the Internet.

Permission is hereby granted for non-profit user groups to republish this content.
PLEASE CREDIT THE AUTHOR AND THE SOURCE: Applecations, publication of the Apple Users' Group, Sydney, Australia

THIS PAGE COPYRIGHT © 2007, ANDREW ROUGHAN